This crate provides a library for high-performance event tracing which is used by
the Rust compiler's unstable -Z self-profile
feature.
The output of a tracing session will be three files:
- A
.events
file which contains all of the traced events. - A
.string_data
file which contains all the strings referenced by events. - A
.string_index
file which mapsStringId
values to offsets into the.string_data
file.
Writing event trace files
The main entry point for writing event trace files is the Profiler
struct.
To create a Profiler
, call the Profiler::new()
function and provide a Path
with
the directory and file name for the trace files.
To record an event, call the [Profiler::record_instant_event()
] method, passing a few arguments:
event_kind
: aStringId
which assigns an arbitrary category to the eventevent_id
: aStringId
which specifies the name of the eventthread_id
: au32
id of the thread which is recording this event
Alternatively, events can also be recorded via the Profiler::start_recording_interval_event()
method. This
method records a "start" event and returns a TimingGuard
object that will automatically record
the corresponding "end" event when it is dropped.
To create a StringId
, call one of the string allocation methods:
Profiler::alloc_string()
: allocates a string and returns theStringId
that refers to itProfiler::alloc_string_with_reserved_id()
: allocates a string using the specifiedStringId
. It is up to the caller to make sure the specifiedStringId
hasn't already been used.